From: Ori Livneh <ori@wikimedia.org>
Date: Sun, 28 Jul 2013 08:22:51 +0000 (-0700)
Subject: $wgHooks: add closure docs & admonition to register handlers early
X-Git-Tag: 1.31.0-rc.0~18929^2
X-Git-Url: http://git.cyclocoop.org//%22http:/%22.attribut_html%28%24lesurls%5B%24numero%5D%29.%22/%22?a=commitdiff_plain;h=c7b8bc69e49b40797f7cda469699dcf47740dba5;p=lhc%2Fweb%2Fwiklou.git

$wgHooks: add closure docs & admonition to register handlers early

This patch takes Tim's advice to amend the doc block for $wgHooks with an
admonition to register hook handlers early. (This was after it was determined
that late registration of a CanonicalNamespace handler was responsible for bug
45031). Since I was already here, I also documented the use of closures with
$wgHooks, fulfilling a @TODO.

Change-Id: Id16148dbfbcc89e0365860e078e089ae541ba08f
---

diff --git a/includes/DefaultSettings.php b/includes/DefaultSettings.php
index 86b08498fd..c638f5230c 100644
--- a/includes/DefaultSettings.php
+++ b/includes/DefaultSettings.php
@@ -5491,17 +5491,24 @@ $wgAuth = null;
  * @endcode
  * - A function with some data:
  * @code
- *     $wgHooks['event_name'][] = array($function, $data);
+ *     $wgHooks['event_name'][] = array( $function, $data );
  * @endcode
  * - A an object method:
  * @code
- *     $wgHooks['event_name'][] = array($object, 'method');
+ *     $wgHooks['event_name'][] = array( $object, 'method' );
+ * @endcode
+ * - A closure:
+ * @code
+ *     $wgHooks['event_name'][] = function ( $hookParam ) {
+ *         // Handler code goes here.
+ *     };
  * @endcode
  *
  * @warning You should always append to an event array or you will end up
  * deleting a previous registered hook.
  *
- * @todo Does it support PHP closures?
+ * @warning Hook handlers should be registered at file scope. Registering
+ * handlers after file scope can lead to unexpected results due to caching.
  */
 $wgHooks = array();